/*
 * MIT License
 *
 * Copyright (c) 2024-2048 冰羽
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */

package cn.star.framework.extend.config;

/**
 * 基于Hikari连接池设置属性<br>
 *
 * @author zhaoweiping
 *     <p style='color: red'>Created on 2024-09-23 11:06:00
 * @since 3.0.0
 */
public interface HikariSettings {

  /**
   * 指定连接是否为只读模式<br>
   * 默认值：false
   */
  String HIKARI_READ_ONLY = "hikari.read.only";

  /**
   * 设置连接的事务隔离级别<br>
   * 默认值：null
   */
  String HIKARI_TRANSACTION_ISOLATION = "hikari.transaction.isolation";

  /**
   * 用于创建指标跟踪器的工厂类<br>
   * 默认值：null
   */
  String HIKARI_METRICS_TRACKER_FACTORY = "hikari.metrics.tracker.factory";

  /**
   * 指定用于创建实际数据库连接的数据源类名<br>
   * 如果你使用的是支持 JDBC 规范的数据库驱动程序，可以使用该选项来指定数据源类名<br>
   */
  String HIKARI_DATA_SOURCE_CLASS_NAME = "hikari.data.source.class.name";

  /**
   * 连接池中允许的最大连接数<br>
   * 默认值：10
   */
  String HIKARI_MAXIMUM_POOL_SIZE = "hikari.maximum.pool.size";

  /**
   * 是否将连接中的内部查询隔离<br>
   * 默认值：false
   */
  String HIKARI_ISOLATE_INTERNAL_QUERIES = "hikari.isolate.internal.queries";

  /**
   * 在 HikariCP 中，setHealthCheckProperties 方法用于设置健康检查属性。健康检查是指连接池对数据库连接的状态进行定期检查，以确保连接的可用性和正确性。
   *
   * <p>该方法接受一个 Properties 对象作为参数，其中包含了要设置的健康检查属性键值对。这些属性可以用于配置健康检查的频率、超时时间、SQL 查询语句等。
   *
   * <p>然而，需要注意的是 HikariCP 的默认健康检查属性是没有指定的。也就是说，默认情况下，HikariCP 不会执行任何特定的健康检查操作。这是因为 HikariCP
   * 认为连接池中的连接应该是已经经过验证和测试的可用连接，不需要通过额外的健康检查来确认其有效性。
   *
   * <p>如果你希望自定义健康检查属性并启用健康检查功能，你可以使用 setHealthCheckProperties 方法来设置相应的属性，并将其传递给 HikariCP
   * 配置对象。具体的属性设置和用法可以参考 HikariCP 文档和相关数据库驱动程序的文档。
   *
   * <p>需要注意的是，配置健康检查属性时，应根据具体的需求和环境进行调整。频繁的健康检查可能会增加数据库的负载，而过长的超时时间可能会导致连接池对失效连接的检测延迟。因此，建议根据实际情况选择合适的健康检查设置以获得最佳的性能和可靠性。
   */
  String HIKARI_HEALTH_CHECK_PROPERTIES = "hikari.health.check.properties";

  /**
   * HikariCP 中用于设置数据源属性的方法。通过该方法，你可以向数据源对象设置一些额外的连接属性，以满足特定的数据库和应用需求。该方法接受一个 Properties
   * 对象作为参数，其中包含了要设置的数据源属性键值对
   */
  String HIKARI_DATA_SOURCE_PROPERTIES = "hikari.data.source.properties";

  /**
   * 连接池初始化失败时的超时时间<br>
   * 默认值：1秒
   */
  String HIKARI_INITIALIZATION_FAIL_TIMEOUT = "hikari.initialization.fail.timeout";

  /**
   * HikariCP 中的一个属性，用于设置异常覆盖类名。该属性指定了一个实现了 SQLExceptionOverride 接口的类，用于覆盖或处理数据库连接过程中可能出现的异常。
   *
   * <p>默认情况下，HikariCP 的 setExceptionOverrideClassName
   * 属性没有指定默认值，即没有启用异常覆盖功能。这意味着在连接过程中，如果出现异常，HikariCP 将会将异常直接抛出给调用方处理。
   *
   * <p>如果你希望自定义异常覆盖行为，并对连接过程中的异常进行特殊处理，可以通过设置 setExceptionOverrideClassName 属性来指定一个实现了
   * SQLExceptionOverride 接口的类。这个异常覆盖类可以自定义异常的处理逻辑，例如重试连接、记录日志、发送警报等
   */
  String HIKARI_EXCEPTION_OVERRIDE_CLASS_NAME = "hikari.exception.override.class.name";

  /**
   * 获取连接的最大等待时间<br>
   * 默认值：30秒
   */
  String HIKARI_CONNECTION_TIMEOUT = "hikari.connection.timeout";

  /**
   * JDBC driver 的类名<br>
   * 默认值：null
   */
  String HIKARI_DRIVER_CLASS_NAME = "hikari.driver.class.name";

  /**
   * 用于指标跟踪的 MetricRegistry 对象<br>
   * 默认值：null
   */
  String HIKARI_METRIC_REGISTRY = "hikari.metric.registry";

  /**
   * 是否注册连接池的 MBeans<br>
   * 默认值：false
   */
  String HIKARI_REGISTER_MBEANS = "hikari.register.mbeans";

  /** 连接初始化时执行的 SQL 语句，可以用于设置连接的特定会话参数或执行其他初始化操作 */
  String HIKARI_CONNECTION_INIT_SQL = "hikari.connection.init.sql";

  /**
   * 用于测试连接是否存活的 SQL 查询语句，默认为 null<br>
   * 如果设置了该选项，HikariCP 会定期执行该查询来检测连接的健康状态
   */
  String HIKARI_CONNECTION_TEST_QUERY = "hikari.connection.test.query";

  /**
   * 在 HikariCP 中，setDataSourceJNDI 方法用于设置数据源的 JNDI 名称。JNDI（Java Naming and Directory Interface）是
   * Java 的命名和目录服务接口，用于在运行时查找和访问命名对象。
   *
   * <p>默认情况下，HikariCP 的 setDataSourceJNDI 属性没有指定默认值，即未启用 JNDI 数据源。这意味着在使用 HikariCP
   * 时，默认情况下你需要通过其他方式配置数据源，例如直接提供 JDBC URL、用户名和密码等。
   *
   * <p>如果你希望使用 JNDI 来配置数据源，可以通过调用 setDataSourceJNDI 方法并传递 JNDI 名称来启用该功能。HikariCP 将尝试从指定的 JNDI
   * 名称中获取数据源
   *
   * <pre>
   *   HikariConfig config = new HikariConfig();
   *   config.setDataSourceJNDI("java:/comp/env/jdbc/mydatasource");
   *   HikariDataSource dataSource = new HikariDataSource(config);
   * </pre>
   */
  String HIKARI_DATA_SOURCE_JNDI = "hikari.data.source.jndi";

  /**
   * 是否允许暂停连接池<br>
   * 默认值：false
   */
  String HIKARI_ALLOW_POOL_SUSPENSION = "hikari.allow.pool.suspension";

  /**
   * 连接验证的超时时间<br>
   * 默认值：5 秒
   */
  String HIKARI_VALIDATION_TIMEOUT = "hikari.validation.timeout";

  /**
   * 用于调度任务的自定义 ScheduledExecutorService<br>
   * 默认值：null
   */
  String HIKARI_SCHEDULED_EXECUTOR = "hikari.scheduled.executor";

  /**
   * 内部泄漏检测的阈值<br>
   * 默认值：0（禁用泄漏检测）
   */
  String HIKARI_LEAK_DETECTION_THRESHOLD = "hikari.leak.detection.threshold";

  /**
   * 用于健康检查的注册表<br>
   * 默认值：null
   */
  String HIKARI_HEALTH_CHECK_REGISTRY = "hikari.health.check.registry";

  /**
   * 保持空闲状态的最小连接数<br>
   * 默认值：10
   */
  String HIKARI_MINIMUM_IDLE = "hikari.minimum.idle";

  /**
   * 连接数据库时使用的用户名和密码<br>
   * 这两个选项通常是必需的，除非在 DataSource 的 URL 中已经包含了认证信息
   */
  String HIKARI_USERNAME = "hikari.username";

  /**
   * 用于创建实际数据库连接的数据源对象<br>
   * 可以通过该选项直接提供一个已经配置好的数据源对象，而不是通过类名进行实例化
   */
  String HIKARI_DATA_SOURCE = "hikari.data.source";

  /**
   * 连接的最大存活时间<br>
   * 默认值：30 分钟
   */
  String HIKARI_MAX_LIFETIME = "hikari.max.lifetime";

  /**
   * 指定连接是否自动提交事务<br>
   * 默认值：true
   */
  String HIKARI_AUTO_COMMIT = "hikari.auto.commit";

  /**
   * 连接数据库时使用的用户名和密码<br>
   * 这两个选项通常是必需的，除非在 DataSource 的 URL 中已经包含了认证信息
   */
  String HIKARI_PASSWORD = "hikari.password";

  /**
   * 数据库的 JDBC URL<br>
   * 默认值：null
   */
  String HIKARI_JDBC_URL = "hikari.jdbc.url";

  /**
   * 连接数据库时要使用的默认 catalog<br>
   * 默认值：null
   */
  String HIKARI_CATALOG = "hikari.catalog";

  /**
   * 连接在池中保持空闲的最长时间<br>
   * 默认值：10分钟
   */
  String HIKARI_IDLE_TIMEOUT = "hikari.idle.timeout";

  /**
   * 用于创建线程的工厂类<br>
   * 默认值：null
   */
  String HIKARI_THREAD_FACTORY = "hikari.thread.factory";

  /**
   * HikariCP 中，setKeepaliveTime 方法用于配置连接的存活时间（keepalive
   * time）。这个属性指定了连接在池中闲置的最长时间，超过这个时间如果连接没有被使用，将被释放并从池中移除。
   *
   * <p>默认情况下，HikariCP 的 setKeepaliveTime 属性未设置默认值。这意味着在默认情况下，连接在池中闲置的时间不受限制，即连接不会因为闲置时间过长而被自动释放和移除。
   *
   * <p>如果你希望对连接的存活时间进行限制，可以通过调用 setKeepaliveTime 方法来设置这个属性。你可以指定一个时间段，超过这个时间的闲置连接将被释放和移除
   */
  String HIKARI_KEEPALIVE_TIME = "hikari.keepalive.time";

  /** 连接的默认模式，用于某些数据库管理系统，默认为 null */
  String HIKARI_SCHEMA = "hikari.schema";

  /**
   * 连接池的名称<br>
   * 默认值：HikariPool-<poolNumber>
   */
  String HIKARI_POOL_NAME = "hikari.pool.name";
}
